fix(564): port the #620 review follow-ups from the merged branch — declared-projection web launch, identity-keyed sessions, opening-tool policy, out-of-artifact web state - #628

Co-authored-by: Zack Jackson <ScriptedAlchemy@users.noreply.github.com>

…e; share one in-flight opening call across concurrent loads

Self-review findings on #628: a session retired by epoch publication while
pages still leased it was deleted from the registry and never closed —
closeSessionWhenUnleased on McpSessionService now closes it at the release
of its last lease (immediately when nothing leases it). The opening-result
cache retains the pending call rather than its settled value, so concurrent
first loads of a mutating opening tool share one tools/call, and a failed
call is dropped so the next load retries. AB8023 documents the /web launch
selection statuses (404 invalid target or no candidate, 409 ambiguous).

Co-authored-by: Zack Jackson <ScriptedAlchemy@users.noreply.github.com>

…he server-owned hub baseline

The overview e2e pinned the server-owned project-event subscriptions at 2
(the Dev Logs tail and the epoch adoption policy). The web host now owns a
third — the artifact.available subscription that retires old-epoch web
sessions (#628) — so the baseline is 3. The page-stream assertions already
measure relative to the captured baseline.

Co-authored-by: Zack Jackson <ScriptedAlchemy@users.noreply.github.com>

…ative-manifest; serialize CompiledCliProjection and option aliases into routes.cli.commands[]

…st (dev /web route 404 after #628 merge)

…rs read the composite root through the manifest (#592 step 3, #555 W2/S3) (#604)

* feat(targets): remove the plugin target from the public target model (#555 S1)

- config/normalize.ts no longer synthesizes a plugin lowering target or a
  shared plugin skill document; loweringHosts is a pure isSkillHost filter.
- adapters/registry.ts registers portable, codex, claude, cursor only;
  adapters/plugin.ts is deleted together with the composite-only capability
  helpers (intersect/union/mergeCapabilityEvidence, capabilityBooleanView).
- targets: ['plugin'] and --target plugin fail with the existing AB4100.
- plugin branches removed from api.ts, pack-inventory, package-build,
  entry-shell, events/projection, lifecycle replay, install/surface,
  install/install, create-agent-bundle options/scaffold, capability JSON,
  and the CLI help text.
- Tests: plugin-bundle.test.ts deleted; plugin rows dropped from the
  adapter, install-surface, normalization and lifecycle suites; acceptance 3
  covered by normalization.test.ts and cli.test.ts.

* feat(build): plan the selected projections into one composite root (#555 S2)

build/build.ts stages every selected host projection into one root at
artifactRoot; build/compose.ts merges byte-identical entries once, fails
same-path collisions with AB4103 in host-name/path order, and refuses
host-scoped components another selected host would discover conventionally
with AB4105. Codex and Cursor hook/MCP documents move beside their manifests;
shared hooks compile to hooks/<name>.<host>.mjs; compiled surfaces are
attributed to the sorted composite identity; the artifact manifest records
only the selected projections. Install, doctor, dev services, eval harnesses,
Workbench, examples, and tests follow the composite root.

* feat(build): AB4106 for mixed advanced-registry selections; validate/inspect judge the composite root; port #569 consumer and docs fixes

- config/validate.ts: AB4106 when an adapter registered on an advanced
  TargetRegistry is selected beside any other target; the built-in host list
  moves to adapters/composite-layout.ts and install/surface.ts imports it.
- build/compose.ts: planComposite returns the plan beside its diagnostics;
  dev/project-service.ts prepare uses it so validate, inspect, dev report
  AB4103/AB4105 exactly where build refuses (caught by the composite-rules
  parity test ported from #569).
- Ported from #569 (superseded): tests/support/mcp-conformance.ts pluginRoot,
  tests/skill-document-service.test.ts decoy, examples/audiobook-curator and
  examples/hooks-and-scripts READMEs, scripts/measure-hook-cold-start.mjs.
- tests/composite-rules.test.ts: layout-independent rules from #569 (four-host
  root, commands/ dialect collision, INSTALL.md sections, validate parity).
- Stale per-host wording: Cursor capability evidence, doctor/types/cursor
  comments, create-agent-bundle README, docs/diagnostics.md, canvas sample.

* test(packed): read the composite root's bin/ and single mcp/ entry in the packed pool

* fix(inspect): describe the same event allowed-targets set the build bakes into a generated-route server; AB4105 trigger names skills

* build: carry #585's MCP App compile diagnostics through the composite root; mcp-apps-compile test selects the portable projection

* test(cli): MCP App compile report attributes the view to the composite selection identity (codex+portable), matching planCompiledMcpApps after the #585 merge

* build: identify the event runtime by the artifact alone; port #569's nested-root and shared-root tests (#592 boundary)

The generated MCP entry and every hook wrapper derived the event runtime's
endpoint id from `<epoch>:<selection identity>:<root>`, so the composite
selection (`claude+codex`) had become runtime identity, and the runtime
took `events.target` as the tool-call lineage host fallback, reading the
selection as a host. Both are projection selection leaking into runtime
identity (#592 §2). The endpoint is now `<epoch>:<root>` on both sides
(entry-shell, hook-contract, `agent-bundle/test` installed harness), the
`target` field leaves `GeneratedRouteMcpEntryOptions` and
`GeneratedEventRuntimeBinding`, and the lineage fallback is the one host a
single-projection root serves, or none for a composite root; `entries.ts`
requires the selection instead of defaulting it from the composite name.

`AB4105` never fired for a skill: normalization gives every skill every
selected target and per-host frontmatter extensions collide as `AB4103`
instead, so the dead skill branch leaves `compose.ts` and the diagnostics,
reference, and framework-mode prose say so. `AGENT_BUNDLE_HOOK_HOST` leaves
the runtime-environment reference (en/zh) and the test env fixtures; `api.ts`
reuses `isBuiltInHost`; `compose.ts` reuses `sortedProjections`; stale
`<target>/…` doc comments in `test/packed.ts` and `routes/graph.ts` name the
root layout.

Ports from #569: install refuses `--from` naming a directory above the plugin
root for all three hosts (`AB7001`, no host CLI runs), doctor lists Claude
plugins from the root `--from` names and never from a nested `claude/`, and
the Codex validator judges only `.codex-plugin/*` in a root shared with
Claude's `.mcp.json` and `hooks/hooks.json`. Lane C's docs parity pass:
tree drawings gain `commands/` and `rules/`, the folder-discovery shield
names all three guarded paths, over-wide code samples re-padded to 90
columns, `AB4808`/`AB4809` prose and the rsc-agent-runtime README describe
one composite root.

* test(prepack): #588's prebuilt payload lands in the composite root (host-packs/runtime/…), not under a target partition

* changeset: the event runtime endpoint is the artifact's alone (#592 boundary)

* review: lineage fallback is the one host whose MCP document lists the server; document AB7001's composite-root trigger

Self-review pass 1 read the fallback as inferring the root's cardinality
from `allowedTargets`. It is `server.targets ∩ selected` — the hosts whose
MCP documents list the server, so the hosts that can have spawned it — and a
Claude-only server in a Claude+Codex root is correctly assumed to be Claude's.
The comment and the two test names now say so. `docs/diagnostics.md` names
`AB7001` in the `AB700x` family row: the host manifest sits directly under
`--from`, never under `<from>/<host>`.

* build: host the composite root's event runtime per selected host's first generated server; judge built-in hosts by adapter identity for the install surface (#578 review)

- planMcpEntriesSurface no longer attaches every event route to the first
  generated-route server: eventRuntimeHosting hosts the runtime in the first
  generated server each selected host's MCP document lists (one process when
  they agree, one per host otherwise) and every hosting server accepts the
  same allowed set; a Claude-only server in a Claude+Codex root no longer
  refuses Codex wrappers while Codex's own server hosts nothing.
- The generated entry carries `hosts` (the selected hosts whose documents
  list the server) separately from `allowedTargets`; the lineage fallback
  reads `hosts`, so a Claude-only server hosting a two-host runtime still
  assumes Claude for an anonymous MCP client (#592).
- TargetRegistry.builtInHost()/builtInHosts() judge the four shipped adapters
  by identity; compose and artifact validation use it for INSTALL.md and
  install.mjs, so an advanced registry's adapter named `portable` earns no
  install surface it never asked for. The pack inventory (manifest names
  only) keeps the name-based requirement it had on main.

* wip(manifest): artifact manifest v2 — projections, routes, executables, distribution; hook index folded into executables.hooks (#592 step 3)

* test(browser): mount each MCP App as one host of the composite selection, never as the selection identity

The browser pool compiles every app once for the project's whole selection
(as the build stages it, #555) but the registry's `target` — the preview
profile and the binding's `target` the page sees — is the host the app
mounts as: the override, or the app's first declared target the project
selects, as before. `claude+codex+portable` had leaked into the binding
(#592) and failed examples/mcp-app's browser-app suite in CI.

* test(manifest): retarget hook and MCP suites at the v2 artifact manifest

The hook-index sidecar is gone; these tests now assert executables.hooks
on agent-bundle.manifest.json and pass the required route graph into build().

* test: migrate manifest coverage to v2

* refactor: read install identity from artifact manifest

* feat: inspect authoritative artifact manifest

* docs: fold #599's per-code diagnostics rows into the composite root — AB4100 lists the four hosts, AB6023/AB6024 and AB7001 describe the one root

* feat(cli): resolve MCP --target from the artifact manifest

serve-app and mcp list|invoke|run default to the only projection that
runs the named server, and inspect reports a built-manifest summary
when one exists at the project's artifact output.

* manifest: routes.cli.routes may hold projected MCP tool routes (routes.mcpCommands)

* test(build-compose): TargetRegistry is constructed, keep the value import

* review: judge built-in hosts by adapter identity in AB4106 and --host-validation; the pack inventory expects exactly the manifested files

- NormalizationTargetRegistry.builtInHost? lets config/validate.ts refuse a
  custom adapter registered under a built-in host's name beside other targets
  (AB4106) the way compose and validate-artifact already judge it; registries
  that cannot tell still judge by name.
- validate --host-validation and build --host-validation select the shipped
  validators through registry.builtInHosts(), so a custom `claude` or
  `portable` adapter is held to no shipped host's contract.
- pack-inventory.ts no longer re-derives the install surface from manifest
  target names: every emitted file is manifested and AB6023/AB6024 already
  judged the surface by identity, so the pack expects what the manifest lists.
- Changeset names the browser pool's `target` option semantics.

* docs: AB4106 judges the shipped adapters by identity

* manifest: hooks[].routeId for event-route wrappers; cross-check CLI command route ids; inspect reads the CLI build root; drop unused imports

* workbench: hook playground rows are manifest hook rows (host, kind, routeId)

* test(workbench): hook client fixture carries manifest hook rows

* docs(manifest): agent-bundle.manifest.json v2 reference; consumers read the composite root through the manifest (#592 step 3, #555 W2/S3)

- New reference page website/docs/{en,zh}/reference/artifact-manifest.mdx
  (+ _meta.json): every section and field of the v2 manifest, who writes it,
  who reads it, the shipped JSON Schema and public reader exports, reserved
  keys not yet emitted, the versioning rule, one abbreviated example.
- install / uninstall / doctor: --from is the composite root; identity and the
  host plugin document come from application + projections[host]; AB7001
  reworded (cli.mdx, installation.mdx, package README).
- serve-app / mcp: --target optional, ambiguity names the choices; inspect
  --json gains output.manifest (cli.mdx, mcp.mdx).
- docs/diagnostics.md: AB7001 and AB60xx family rows; new "Artifact manifest
  coherence (AB6039–AB6040)" section; AB6018 reads executables.hooks[].
- Stale statements: agent-bundle.hooks.json sidecar removed from artifact
  trees and prose (index, project-structure, targets-artifacts, hooks,
  entry-conventions); targets rows -> projection rows.
- Changeset .changeset/592-authoritative-manifest.md (agent-bundle minor).

* feat(validate): AB6039/AB6040 manifest coherence lane over the v2 artifact manifest (#592 step 3)

New `src/build/validate-artifact-manifest.ts`, wired into `validateArtifact`
beside the hook and MCP coherence validators and gated on a parsed manifest
whose file table verified (no AB6004), so neither code fires on top of
AB6000/AB6001/AB6004 noise.

AB6039 (error) — manifest section coherence, what the parser cannot know
without the adapter registry or the tree:
- executables.bins[].path|worker, scripts[].path|worker,
  mcpServers[].entry.path|worker, mcpServers[].apps[].path must be direct
  files of the row's host layout (cliBin, scripts, mcpEntries, mcpApps);
  hooks[] stays with AB6018, which already holds it to hookWrappers.
- a route-generated server (routes.servers[] mode 'generated' with routes)
  whose executables.mcpServers[] row is not 'compiled' or carries another name.
- projections[host].documents.mcp / .hooks must name the document the host's
  runtime / hook contract reads; a row listing a host without an MCP runtime
  or without an MCP document.
- the host MCP document and the rows listing that host declare the same
  server names, each with the transport its row records.

AB6040 (error) — host document disagrees with the manifest identity:
- documents.plugin name/version vs application.name/version.
- documents.marketplace name vs projections[host].marketplace.name; a
  marketplace document the projection does not record (the parser already
  refuses the reverse).
- a host document that is not a strict JSON object cannot be proven.

Both are error severity because a consumer acting on the manifest would
install or launch something the tree does not contain.

Tests: tests/artifact-manifest-coherence.test.ts builds one composite root
(claude, codex, cursor, portable; compiled + command + remote MCP servers;
three marketplaces) and forges one disagreement per case with the manifest
re-serialized and the file table re-hashed, asserting exactly one code.

* fix: resolve MCP documents from artifact manifest

* docs(manifest): hooks[].routeId and projected CLI tool routes (en, zh)

* test: exercise host validation by adapter identity through validate --artifact and build --host-validation

The identity test validated the project root, which never enters host
validation; validate the built custom root as an artifact instead, and
build a custom adapter named claude with a runner spy that must not be
spawned. AB6024's row names the shipped cursor/portable adapters by
identity, as the validator judges.

* Ship a JSON Schema for agent-bundle.manifest.json (#592 step 3)

Add schemas/agent-bundle.manifest.schema.json (draft 2020-12, closed keys
at every level, $defs per manifest shape, "present exactly when" rules as
if/then/else) and publish it through package.json `files` and the
`./schemas/agent-bundle.manifest.schema.json` export.

src/build/manifest-schema.ts imports the JSON, deep-freezes it as
`artifactManifestSchema`, and compiles it once with Ajv 2020 strict mode
(strictRequired relaxed for the conditionals) behind
`validateArtifactManifestSchema(value): readonly string[]`; both are
exported from src/api.ts and src/index.ts. The Rslib bundle inlines the
JSON, so dist needs nothing from the packed schemas directory.

src/schemas/ajv-issues.ts now installs ajv-formats, accepts Ajv options,
and owns the shared `compareSchemaIssues` comparator (lifted from
agent-skills/contract.ts) plus `formatSchemaIssue`.

scripts/dist-freshness.mjs counts the schemas directory as an agent-bundle
build input, since the JSON is compiled into dist.

tests/manifest-schema.test.ts checks a populated and a minimal hand-built
manifest against both validators, sweeps every object for delete /
unknown-key / retype mutations asserting parser-schema agreement with a
two-entry documented allowlist, pins the parser-only rules (sorted arrays,
cross-references, digests, runtime floor, npm name and semver validity)
as accepted-by-schema, pins the schema-encoded rules as rejected by both,
and asserts $id, $schema, manifestVersion const, freezing, and the
package.json wiring.

* test: validate --artifact takes the project root too

* validate: manifest coherence judges MCP rows against the MCP lane's single document read; fixtures follow host layouts

* schema: hooks[].routeId, projected CLI tool routes; writer output validates against the shipped schema; changeset names #604

* doctor: AB7306 recovery names the composite root and manifest projection

* review fixes: reciprocal contract binding, ENOENT-only missing manifest, marketplace pointer existence, projection document pointers judged by the host contract, doctor proof over the built root, stale AB6018/AB7001 prose

* validator: judge document→row MCP coherence by built-in host identity; integration expectations for AB6039/AB6040 and the mcp run refusal

* manifest: projections[].builtInHost records the shipped adapter identity; install/doctor and the installed harness key on it, the validator cross-checks it (AB6039), inspect reports it

* test: mcp-probe fixture records the claude adapter identity

* fixtures record built-in identity; advanced-adapter MCP documents own servers the manifest never rowed; inspection projections in the workbench proof

* validator: the coherence lane reuses the contracts the target-contract lane fetched; no registry re-entry after evidence snapshots

* docs: architecture page describes manifest v2 (#597 follow-up); export ArtifactManifestRouteContract types; cli test imports at top

* feat(workbench): project manifest application explorer

* Prove artifact-manifest paths stay relocatable when the composite root moves.

The writer already emitted root-relative POSIX paths; the parser now also
rejects a Windows drive-letter prefix, and a real build proves the bytes
never encode the machine and every reader still works after rename.

* paths: one relocatable-path rule (core/paths isRelocatablePosixPath) shared by the manifest parser and the writer

* refactor(build): serialize manifest from compiler plans

* docs: describe authoritative manifest generation

* manifest: split operational compiler facts into compiler.recordVersion 1

Keep timings, cache keys, adapter revisions, source-input hashes, and other
run metadata out of the public artifact contract so a compiler refactor never
forces a manifestVersion bump.

* readers: consume manifest.compiler for operational facts

Move validator, pack inventory, eval, inspection, and the installed harness
onto compiler.project / provenance / adapters / agentSkills so consumer
surfaces keep reading only the public contract.

* docs: document the public contract vs compiler record

Restructure the artifact-manifest pages and the targets outline around
manifestVersion and compiler.recordVersion, and mention routes.contracts[]
in the authoritative-manifest changeset.

* test: read provenance and compiler.project after the manifest split

Leftover fixture helpers still typed adapter facts onto projections and
asserted files[].sourceInputs / manifest.project on the public contract.

* docs(architecture): no separate coherence pass; AB6010 carries adapter identity

* test: explorer fixture follows the compiler record split

* rstest: drop the deleted coherence test from the integration list

* docs(architecture): public contract vs compiler record; explorer projection

* Add inspect --artifact so a copied composite root is read through the manifest alone.

* fix: trust manifest inventory for installs

* docs: describe authoritative install inventory

* manifest: MCP/hooks pointers come from the adapter runtime and hook contracts; explorer tolerates route-less servers; tests follow the compiler split

* deslop: reuse errorMessage from core/errors, drop dead projectionFor export, fix orphaned doc comment

- manifest-file.ts: replace private describe helper with the existing
  errorMessage from core/errors.ts (helper-before-writing rule)
- manifest.ts: delete projectionFor, exported with no importer anywhere
  (the coherence test defines its own throwing variant)
- manifest-routes.ts: move the artifactRoutesFor doc comment off
  artifactRouteContractFor, where it was stranded as a second docblock

Co-authored-by: Zack Jackson <ScriptedAlchemy@users.noreply.github.com>

* fix: reindex derived artifact variants

* docs: explain variant manifest reindexing

* deslop: drop type-bypassing casts, restating comments, and repetitive changeset prose

* manifest: carry the web section through v2 — schema, referenced-path rule, doctor reads it from the parsed manifest

* tests: preflight artifact graph reads hook rows from the manifest, not the removed sidecar

* tests: compiler-evidence fixture supplies the route graph the manifest writer requires

* review: doctor --from keeps AB7001 from the identity reader; mcp run launches the host document's own line, cross-checked against the manifest entry; relocatable proof covers web.apps[].entry

* tests(packed): provenance lives on compiler.provenance; the packed MCP fixture declares its portable projection identity and server row

* Address second self-review: keep AB7001 in doctor, launch host MCP lines verbatim, reject drive paths in schema, cover web entries in relocation proof

* feat(manifest): serialize definePrebuilt payloads as distribution.payloads[] (#630 absorbed)

* chore: deslop merge delta (gpt-5.6-sol-medium, 1 edit)

* Address merge-delta review: payload host-filtering proof, transport on inspection MCP rows, index-based payload location, diagnostics prose

* web-host: read declared projections from manifest v2 projections[].host (dev /web route 404 after #628 merge)

* feat(manifest): record event route execution

* Pin a strict closed-key inventory for manifest v2 and surface payload runtimeDependencies on inspect.

An old closed reader rejects any unknown key, so adding an optional public field is not compatible — the inventory fixture fails until the version bumps, and artifact-only consumers read packages from distribution.payloads[].runtimeDependencies.

* test: add combined manifest proof

* manifest-key-inventory: merge narrowed row properties over the shared $def; regenerate v2 inventory with routes.events[].execution

* combined proof: assert routes.events[].execution from the built manifest

* docs: readers refuse any other manifestVersion in either direction

* manifest: one launch record for compiled MCP servers

`executables.mcpServers[]` rows of kind `compiled` carry `launch`
({ args, entry, env, worker? }) in place of `entry`; `args[]` records the
author's declaration as `artifact` root-relative paths (plugin-root-anchored)
or `literal` values whose tokens the launcher expands. `web.apps[]` drops its
copied `entry`/`args`/`env` and names the compiled server instead; the parser
cross-checks the reference, the files[] rows, and artifact arguments.

The launch types live in `web-host/manifest.ts` (bundled into every plugin
bin) and `build/manifest.ts` imports them; `readWebManifestDocument` returns
`{ hosts, launches, web? }` so `<plugin> web` resolves the App's launch
through the record. Schema, docs (en+zh), changeset clause, and the packed,
relocatable, and unit proofs follow.

* combined proof: assert executables.mcpServers[].launch; bare plugin-data token

* manifest: prebuilt MCP servers carry the same launch record (kind 'prebuilt'), so web Apps on definePrebuilt servers keep working through one record

* deslop: 5 edits

* Honor manifest launch records in mcp run fallback; web reader requires manifestVersion 2; pin proof wording; prebuilt args/env launch coverage

* Rewire the read-only state-root proof to the manifest launch record

* Remove the prebuilt launch test's temporary home

* Anchor the manifest-only mcp run fallback on the durable plugin root; document the lean web reader and optional web key

* Document the lean web reader as the one non-parser consumer

* Locate the declared state root through the installed manifest's MCP pointer; admit the compile evidence record

* Deslop the state-root rewire; state the inherited state-root fallback

* fix(manifest): lean web reader rejects unsupported versions, duplicate server identities, malformed launch and projection rows; reindex refuses compiled files and compile evidence

* test(workbench): avoid terminal close locator race

* test(manifest): combined proof checks compile evidence survives reindex and install

* chore: deslop pass over the reader/reindex delta

* fix(manifest): launch records name indexed bytes only in both readers; copies re-measure to the verified inventory

* test(manifest): match server-name diagnostics

* fix(manifest): the runtime-owned state root is reserved everywhere — AB4741 for payloads, files[] parser and schema, installers

* fix(manifest): one files[] path rule for both readers — never the manifest, the runtime state root, or the install receipt entry

* chore: deslop the post-review reader/evidence delta

---------

Co-authored-by: Ubuntu <zack@ubuntu-main.local>
Co-authored-by: Zack Jackson <ScriptedAlchemy@users.noreply.github.com>